[Github] Git Commit Convention

Amaranth2023년 07월 02일

Git Commit Convention

Git 커밋 메시지 컨벤션이란 프로젝트의 참여자들이 일관된 형식의 커밋 메시지를 작성하기 위한 규칙이다.

Git 커밋 메시지는 코드 변경 사항을 요약하여 전달하는 역할을 한다. 만약 개발자들이 서로 다른 방식으로 커밋 메시지를 작성하면 메시지의 가독성이 떨어지고, 문제 발생 시 이력을 추적하기가 어려워진다. 그래서 프로젝트를 시작하기 전 팀 내의 Git 커밋 메시지 컨벤션을 정하는 것이 중요하다.

Git 커밋 컨벤션을 통해 커밋 메시지의 형태를 일관되게 유지하면 다음과 같은 장점을 얻을 수 있다.

가독성을 높일 수 있다.

⇒다른 개발자의 작업 내역이나 변경 사항을 쉽게 파악할 수 있어 코드 리뷰 및 버그 수정 과정에서 불필요한 의사소통 비용을 줄일 수 있다.
변경 이력 추적 및 문제 해결 속도 향상

⇒ 코드 변경 이력을 효율적으로 추적할 수 있어 문제가 발생했을 때 더 빠르게 원인을 찾아 수정할 수 있다. 이로써 전반적인 프로젝트의 안정성을 높일 수 있다.

Convention이기 때문에 프로젝트의 스펙에 따라, 팀에 따라 얼마든지 달라질 수 있다. 실제로도 다양한 바리에이션이 존재한다.

한 가지 예시를 두고 설명하는 편이 좋을 것 같아서 Udacity Git Commit Message Style Guide를 참고하여 이 글을 작성하였다.

Udacity Git Commit Message Style

크게 제목(header), 본문(body), 꼬리말(footer)로 나누고 각 파트는 빈 줄을 두어 구분한다.

type: [#issueNumber] - Subject  // 제목

body // 본문

footer // 꼬리말

type : 어떤 의도로 커밋했는지를 명시한다.
subject : 마침표를 찍지 않고, 영문 표기의 경우 동사(원형)를 가장 앞에 두고 첫 글자를 대문자로 표기한다.(최대 50자)
body : 긴 설명이 필요한 경우 작성한다. 어떻게 했는지가 아니라 무엇을, 왜 했는지 작성한다. (최대 75자)
footer : issue tracker id를 명시하고 싶은 경우 작성한다.

제목

타입은 'type: Subject'의 형태이고, :(콜론) 뒤에만 space가 있는 것을 유의해야 한다.

Type

Type 이름	설명
Feat	새로운 기능을 추가할 경우
Fix	버그를 고친 경우
Design	CSS 등 사용자 UI 디자인 변경
!BREAKING CHANGE	커다란 API 변경의 경우
!HOTFIX	급하게 치명적인 버그를 고쳐야하는 경우
Style	코드 포맷 변경, 세미 콜론 누락, 코드 수정이 없는 경우
Refactor	프로덕션 코드 리팩토링
Comment	필요한 주석 추가 및 변경
Docs	문서를 수정한 경우
Test	테스트 추가, 테스트 리팩토링(프로덕션 코드 변경 X)
Chore	빌드 태스트 업데이트, 패키지 매니저를 설정하는 경우(프로덕션 코드 변경 X)
Rename	파일 혹은 폴더명을 수정하거나 옮기는 작업만인 경우
Remove	파일을 삭제하는 작업만 수행한 경우

Subject

: 코드 변경 사항에 대한 짧은 요약. 다음의 규칙을 따른다.
1. 제목의 처음은 동사 원형의 명령어로 시작한다.(영문의 경우 첫 글자는 대문자로 작성한다.)
2. 총 글자 수는 50자 이내로 작성한다.
3. 마지막에 특수문자(.!?)는 삽입하지 않는다.
4. 제목은 개조식 구문으로 작성한다.
  - 완전한 서술형 문장이 아니라 간결하고 요점적인 서술을 의미한다.

본문

한 줄당 72자 내로 작성한다.
본문 내용은 양에 구애받지 않고 최대한 상세히 작성한다.
본문 내용은 어떻게 변경했는지보다 무엇을, 왜 변경했는지를 설명하는 데 초점을 맞춘다.

꼬리말

꼬리말은 optional이고 **이슈 트래커 ID(=이슈번호)**를 작성한다.
꼬리말은 "이슈 유형: #이슈 번호" 형식으로 사용한다.
여러 개의 이슈 번호를 적을 때는 쉼표로 구분한다.
이슈 트래커 유형은 다음 중 하나를 사용한다.

Fixes: 이슈 수정중 (아직 해결되지 않은 경우)
Resolves: 이슈를 해결했을 때 사용
Ref: 참고할 이슈가 있을 때 사용
Related to: 해당 커밋에 관련된 이슈번호 (아직 해결되지 않은 경우)

이러한 컨벤션에 따라 작성된 커밋 메시지의 예시는 다음과 같다.

Feat: "추가 로그인 함수"

로그인 API 개발

Resolves: #123
Ref: #456
Related to: #48, #45

커밋 메시지 이모지(feat. Gitmoji)

시각적으로 커밋 의도를 드러내기 위해 커밋 메시지에 Gitmoji를 포함하기도 한다.

Emoji	Description
🎨	코드의 형식 / 구조를 개선 할 때
📰	새 파일을 만들 때
📝	사소한 코드 또는 언어를 변경할 때
🐎	성능을 향상시킬 때
📚	문서를 쓸 때
🐛	버그 reporting할 때, @FIXME 주석 태그 삽입
🚑	버그를 고칠 때
🐧	리눅스에서 무언가를 고칠 때
🍎	Mac OS에서 무언가를 고칠 때
🏁	Windows에서 무언가를 고칠 때
🔥	코드 또는 파일 제거할 때 , @CHANGED주석 태그와 함께
🚜	파일 구조를 변경할 때 . 🎨과 함께 사용
🔨	코드를 리팩토링 할 때
☔️	테스트를 추가 할 때
🔬	코드 범위를 추가 할 때
💚	CI 빌드를 고칠 때
🔒	보안을 다룰 때
⬆️	종속성을 업그레이드 할 때
⬇️	종속성을 다운 그레이드 할 때
⏩	이전 버전 / 지점에서 기능을 전달할 때
⏪	최신 버전 / 지점에서 기능을 백 포트 할 때
👕	linter / strict / deprecation 경고를 제거 할 때
💄	UI / style 개선시
♿️	접근성을 향상시킬 때
🚧	WIP (진행중인 작업)에 커밋, @REVIEW주석 태그와 함께 사용
💎	New Release
🔖	버전 태그
🎉	Initial Commit
🔈	로깅을 추가 할 때
🔇	로깅을 줄일 때
✨	새로운 기능을 소개 할 때
⚡️	도입 할 때 이전 버전과 호환되지 않는 특징, @CHANGED주석 태그 사용
💡	새로운 아이디어, @IDEA주석 태그
🚀	배포 / 개발 작업 과 관련된 모든 것
🐘	PostgreSQL 데이터베이스 별 (마이그레이션, 스크립트, 확장 등)
🐬	MySQL 데이터베이스 특정 (마이그레이션, 스크립트, 확장 등)
🍃	MongoDB 데이터베이스 특정 (마이그레이션, 스크립트, 확장 등)
🏦	일반 데이터베이스 별 (마이그레이션, 스크립트, 확장명 등)
🐳	도커 구성
🤝	파일을 병합 할 때

마무리

해당 컨벤션은 한 가지 예시일 뿐이며, 실제 커밋 컨벤션은 제품과 팀의 특성에 따라 고민해보고 결정하는 것이 좋다.

필자가 자주 사용했던 커밋 메세지 형식은 다음과 같다.

커밋 타입: 커밋 내용 요약

- 커밋 상세 내용1
- 커밋 상세 내용2
...

#이슈번호

내가 지금까지 봐왔던 커밋 컨벤션 대부분은 type(feat, refactor, fix, …)을 사용했었는데, type 별 상세 분류를 프로젝트 성격에 맞게 변형하기도 한다.

예를 들어, 필자가 이전에 참여했던 프로젝트의 웹 프론트엔드 팀에서는 css 변경사항에 대한 커밋을 식별하기 위해 design이라는 타입을 도입했었다.

참고 자료

Udacity Git Commit Message Style Guide

[협업] 협업을 위한 git 커밋컨벤션 설정하기

Git 커밋 메시지 컨벤션은 왜 중요할까? | 요즘IT

좋은 커밋을 작성하는 법

github